home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / find.arc / FIND.DOC < prev   
Encoding:
Text File  |  1987-10-25  |  8.1 KB  |  151 lines
  1. -------------------------------------------------------------------------------
  2. *****************      ************      ********    ******      *********
  3. *****************      ************      ********    ******      ***********
  4.  ****        ****          ****            ****        **         ****    ****
  5.  ****                      ****            **  **      **         ****     ****
  6.  *********                 ****            **    **    **         ****     ****
  7.  ****                      ****            **      **  **         ****     ****
  8.  ****                      ****            **        ****         ****    ****
  9. *******                ************      ******    ********      ***********
  10. *******                ************      ******    ********      *********
  11. -------------------------------------------------------------------------------
  12. FIND:  A utility to search any number of files for a pattern match specified on
  13.        the command line.  In addition,  the following command line switches are
  14.        available  (most are the same as for the  DOS FIND utility documented in
  15.        the DOS manual):
  16.     
  17.         o [/v] lists all lines NOT containing pattern match
  18.         o [/c] displays only count of lines containing pattern match
  19.         o [/n] lists relative line number along with matching line
  20.         o [/s] makes pattern search case sensitive (case insensitive is
  21.                default)
  22.         o [/a] activates a verbose reporting mode.  Normally, if a file
  23.                contains no matches, nothing is reported to the user. In
  24.                this verbose mode, All file processing is reported.
  25.         o [/b] allows searching binary files. The output is reported in
  26.                byte format (HEX and ASCII) iso line format.  The /n and
  27.                /v options are disabled if this option is selected.
  28.  
  29.  
  30. Usage: find [/v][/c][/n][/s][/a][/b] "pattern" [<filespec> <filespec> ... ]
  31.  
  32.        (items in square brackets are optional)
  33.  
  34.        where  <filespec> is a file specification that may contain wildcards and
  35.        paths of the form :
  36.  
  37.        [d:][path]filename[.ext]
  38.  
  39.     
  40. Improvements over the original DOS filter include :
  41.     
  42.        o Command  line  parsing  has been  improved so  that  parameters can be
  43.      entered in any order the user wishes (i.e. FIND/N/S "PATTERN" FILE.EXT
  44.      or  FIND/N FILE.EXT "PATTERN"/S  are both acceptable).  In addition no
  45.      "white space"  is required  between the  quotes for the string pattern
  46.      and the  rest of the  command line  (i.e. the above example could have
  47.      been entered FIND/N/S"PATTERN"FILE.EXT).
  48.        o File specifications may include wildcards (? or *).
  49.        o String patterns may include wildcards (via [?] character).
  50.        o Pattern matching is case insensitive by default.  Case sensitivity can
  51.      be restored via the [/s] switch.
  52.        o Verbose reporting mode option via the [/a] switch. Normally files with
  53.          no matches are not reported to the user. In this verbose mode all file
  54.          processing is reported.
  55.        o Ability to search binary files via the [/b] switch  (output will be in
  56.      DEBUG style  HEX format).  The [/v] and [/n] switches are disabled for
  57.      this option.
  58.        o Ability to search for special characters (via [\] char).
  59.        o Properly treats tabs as "white space" on command line.
  60.        o Corrects error in original  FIND routine that accumulated a line count
  61.      error every buffer refill.
  62.        o Dynamically allocates  and utilizes user's memory for  buffer space to
  63.      optimize file I/O (old routine used fixed buffers).  This also reduces
  64.      the load file size significantly.
  65.        o Retains use of "STD" I/O devices to support redirection.
  66.        o Structured for '.COM' format iso '.EXE'.
  67.  
  68.     
  69. Notes: If a <filespec> was not specified,  it is assumed that the input to this
  70.        program has been redirected, and thus reads its input from the 'Standard
  71.        Input Device' (file handle 0).  If there was no redirection, the program
  72.        will detect this and output a 'Usage' error message.
  73.  
  74.        The specified string pattern is a normal ASCII string with the following
  75.        exceptions (based on C language escape sequences):
  76.  
  77.         o [\b] will match a <BACKSPACE> character   [^H]
  78.         o [\f] will match a <FORMFEED> character    [^L]
  79.         o [\n] will match a <CR><LF> pair (NEWLINE) [^M][^J]
  80.         o [\r] will match a <CR> character        [^M]
  81.         o [\t] will match a <TAB> character        [^I]
  82.         o [\\] will match a <BACKSLASH> character.
  83.         o [\] followed by any character other than the above will match
  84.               that character (i.e. [\?] or [\"] etc).
  85.         o [?] is a positional wildcard.  A  [?]  at any position in the
  86.               string will match any character at that position.
  87.  
  88.        Note also that to maintain compatibility with the original  FIND filter,
  89.        consecutive double quotes are treated the same way as  [\"]  -  they are
  90.        read as a single string character and not as a string delimiter.
  91.  
  92.        The command line switch character can be modified via a  [SWITCHAR=char]
  93.        statement in the CONFIG.SYS file (note that this is not being officially
  94.        supported by either  Microsoft or  IBM and should only be used at user's
  95.        discretion). If the user specifies a  SWITCHAR=- in the CONFIG.SYS file,
  96.        DOS will adopt the UNIX convention for switch specification (i.e. use of
  97.        a '-' iso '/'). This also has the side benefit of making DOS recognize a
  98.        UNIX style  directory pathname convention  (i.e.  paths can be specified
  99.        with either a  '/' or a '\').  This utility checks for and uses whatever
  100.        switch character was specified to DOS via the  SWITCHAR statement.  Note
  101.        also that  SWITCHAR is NOT available in  DOS versions 3.00 and above. In
  102.        addition, it has been brought to my attention that certain more esoteric
  103.        versions of DOS (i.e. CCP/M),  do not have a CONFIG.SYS capability.  The
  104.        following patch  will modify  FIND.COM to use  whatever switch character
  105.        the user desires. It is assumed the user is familiar with the process of
  106.        patching files with DEBUG.
  107.  
  108.             Location    |     Was     |     Now
  109.         ----------------+-------------+-------------
  110.               0113    |     CD      |     B2
  111.               0114    |     21      |     2D
  112.  
  113.     Location 0114 is to be changed to the  ASCII code of whatever character
  114.     is required. Hex 2D above is the ASCII code for the '-' character.
  115.  
  116.     Note that these locations are valid for FIND.COM Version 1.3 ONLY.
  117.  
  118.  
  119. Error messages :
  120.  
  121.        o 'Incorrect DOS version'
  122.       - this utility requires DOS 2.00 or higher.
  123.        o 'Usage: FIND [/v][/c][/n][/s][/a][/b] "pattern" [<filespec> ... ]'
  124.       - improper command line syntax. This gives proper usage.
  125.        o '%FIND: Syntax error in string pattern'
  126.       - improper string specification (missing quote[s] in string).
  127.        o '%FIND: File not found <filnam.ext>'
  128.       - specified file not found or could not open.
  129.        o '%FIND: Read error in <filnam.ext>'
  130.       - encountered a read error while reading <filnam.ext>.
  131.        o '%FIND: Invalid switch <s>'
  132.       - specified switch is not recognized by FIND.
  133.        o '%FIND: Insufficient memory'
  134.       - insufficient memory for dynamic buffers (a minimum of 512 bytes are
  135.         required AFTER the program has been loaded into memory).
  136.        o '%FIND: Error writing to STDOUT'
  137.       - usually get this error if STDOUT has been redirected to file and
  138.         there is no more disk space.
  139.  
  140. -------------------------------------------------------------------------------
  141. FIND                  (c) Copyright 1987               StarSoft Systems
  142. Version 1.3                               4844 King Edward
  143. Fulvio J. Castelli          October 1st 1987               Montreal, CANADA
  144. -------------------------------------------------------------------------------
  145. IF YOU FIND THIS UTILITY IN ANY WAY USEFUL, WE KINDLY REQUEST A CONTRIBUTION OF
  146. $10.00 (U.S.) SENT TO THE ABOVE ADDRESS. HAVING DONE SO, YOU WILL AUTOMATICALLY
  147. BECOME A REGISTERED USER,  AND WILL BE ENTITLED TO ALL FURTHER  UPDATES AS THEY
  148. ARE MADE AVAILABLE.  WE ARE  DISTRIBUTING THIS  SOFTWARE UNDER THE  'SHAREWARE'
  149. PHILOSOPHY  AND RELY  STRICTLY  ON THE  SUPPORT  OF OUR  USERS TO  MAINTAIN IT.
  150. -------------------------------------------------------------------------------
  151.